home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / hardware / mccontrol / modules / modules.doc < prev    next >
Text File  |  1999-11-29  |  12KB  |  325 lines
  1. ;----------------------------------------------------------------------------
  2. ;This is not an documentation how to use the .mcm modules in your own
  3. ;software! Its an documentation about how to write modules for other
  4. ;card reader.
  5. ;----------------------------------------------------------------------------
  6. TABLE OF CONTENTS
  7.  
  8. MCControlModule/General
  9. MCControlModule/Module_Delay
  10. MCControlModule/Module_Open
  11. MCControlModule/Module_FrameOpen
  12. MCControlModule/Module_FrameClose
  13. MCControlModule/Module_ReadCommand
  14. MCControlModule/Module_WriteCommand
  15. MCControlModule/Module_PADOpen
  16. MCControlModule/Module_PADClose
  17. MCControlModule/Module_PADCommand
  18. ;----------------------------------------------------------------------------
  19.  *General*
  20.  
  21. First the main structure:
  22.  
  23.         RSRESET
  24. Module_RTS                   rs.w 1 ;to avoid crash when user is starting module
  25. Module_Version               rs.w 1 ;Currently 1
  26. Module_ID                    rs.l 1 ;must be "MCCM"
  27. Module_Flags                 rs.l 1 ;Unused Flags must be ZERO
  28. Module_Exec_Base             rs.l 1 ;Filled by MCControl
  29. Module_Dos_Base              rs.l 1 ;Filled by MCControl
  30. Module_Intuition_Base        rs.l 1 ;Filled by MCControl
  31. ;--- Card Data
  32. Module_DelayReadByte         rs.l 1 ;Filled by MCControl
  33. Module_DelayReadBit          rs.l 1 ;Filled by MCControl
  34. Module_DelayWriteByte        rs.l 1 ;Filled by MCControl
  35. Module_DelayWriteBit         rs.l 1 ;Filled by MCControl
  36.                              rs.l 10 ;reserved (must be ZERO)
  37. ;--- Jump Table
  38. Module_Delay                 rs.w 3 ;Filled by MCControl
  39. Module_Open                  rs.w 3
  40. Module_Close                 rs.w 3
  41. Module_FrameOpen             rs.w 3
  42. Module_FrameClose            rs.w 3
  43. Module_ReadCommand           rs.w 3
  44. Module_WriteCommand          rs.w 3
  45. Module_PADOpen               rs.w 3
  46. Module_PADClose              rs.w 3
  47. Module_PADCommand            rs.w 3
  48.                              rs.w 3*10 ;reserved
  49. Module_SIZEOF                rs.b 0
  50. ;----------------------------------------------------------------------------
  51.  BITDEF Module,Delay,0         ;Tell MCControl you require timing data.
  52.                                ;This will be used to disable/hide delay
  53.                                ;slider.
  54.  BITDEF Module,Device,1        ;Tell MCControl you require an Device/Unit
  55.                                ;selector
  56.  BITDEF Module,MultiPage,2     ;Tell MCControl you support MultiPage support
  57. ;----------------------------------------------------------------------------
  58. Module_Error_OpenDevice    = 1
  59. Module_Error_NotCompatible = 2   ;If hardware supports identification!
  60. Module_Error_OutOfMemory   = 20
  61. ;----------------------------------------------------------------------------
  62.  
  63.  
  64.  NOTES 
  65.  
  66.    The exec, dos and intuition bases are free. Just use them.  This  saves
  67.    memory,  time and of cource code size. The card data is for free usage,
  68.    too.
  69.  
  70.    You must implement port and device allocation into Module_Open()! Don´t
  71.    try  to  play  with  the hardware without owning the right to do so. If
  72.    possible try to use parallel.device or serial.device. (The user defined
  73.    device will be given during Module_Open().
  74.        
  75.    Its not required to create an real jumptable, by using JMPs. Feel free,
  76.    to use an BRA followed by an NOP. (See RamCard.mcm)
  77.        
  78.    Its strongly  required  to  implement  all  given  jumps.  (except  the
  79.    Module_Delay).  If  you  don´t require FrameOpen, then jump (branch) to
  80.    Module_RTS or just use an RTS followed by 2 NOPs!
  81.  
  82.    Implement the code as fast as possible, because its used for many times
  83.    during reading and writing memory cards. Try to avoid overhead by using
  84.    Module_Open, or if not possible Module_FrameOpen.
  85.        
  86.    Your reader expects only a frame number and returns a  complete  frame?
  87.    Well,  this  isn´t  realy a problem. Feel free to use the sourcecode of
  88.    the RamCard.mcm. At the end you´ll find two routines  for  reading  and
  89.    writing the whole frame.
  90.  
  91.    If you need help then ask me and I am telling you what to  do.  If  you
  92.    don´t  know how to code a driver then send me your information and I´ll
  93.    do my very best.
  94.  
  95. ;----------------------------------------------------------------------------
  96. MCControlModule/Module_Delay
  97.  
  98.    NAME
  99.                  Module_Delay
  100.         
  101.    SYNOPSIS
  102.                  Module_Delay(Time);
  103.                               D0
  104.  
  105.                  Module_Delay(ULONG);
  106.  
  107.    FUNCTION
  108.                  Standard MCControl timer for high speed delay
  109.                  calculations.
  110.  
  111.    INPUTS
  112.                  Time faktor (use Module_Delay#? field for getting
  113.                  values. The delay is on all systems nearly identicaly.
  114.    WARNING
  115.                  Due multi tasking it is possible that this delay is
  116.                  much longer, but this should be no problem.
  117. ;----------------------------------------------------------------------------
  118. MCControlModule/Module_Open
  119.  
  120.    NAME
  121.                  Module_Open -- open and inits the module
  122.  
  123.    SYNOPSIS
  124.                  Error   = Module_Open(Device, Unit)
  125.                  D0                    a0,     d0
  126.  
  127.                  (ULONG) = Module_Open(*UBYTE,ULONG)
  128.    FUNCTION
  129.                  Open the required device and alloc additional memory
  130.                  if needed.
  131.    INPUTS
  132.                  Device: Pointer on device name (STRING IS READ ONLY!!!)
  133.                  Unit:   Unit of the given device
  134.    RESULT
  135.                   0 = No Error
  136.                   1 = Open device error
  137.                   2 = Not compatible
  138.                  20 = Out of memory
  139.  
  140.                  Other results are not allowed!!
  141.    NOTES
  142.                  Device and Unit are only valid if the Device-Flag within
  143.                  the module structure (Module_Flags) is set.
  144.  
  145.    SEE ALSO
  146.                  Module_Close()
  147. ;----------------------------------------------------------------------------
  148. MCControlModule/Module_Close
  149.  
  150.    NAME
  151.                  Module_Close -- free all data and close all devices.
  152.  
  153.    SYNOPSIS
  154.                  Module_Close()
  155.  
  156.    FUNCTION
  157.                  Close all devices and free all allocated memory .
  158.    NOTES
  159.                  Module_Close must be save to be called more than
  160.                  one time. This means you must detect an closing of
  161.                  an just closed module. In this case you must return
  162.                  without any action.
  163.    SEE ALSO
  164.                  Module_Open()
  165. ;----------------------------------------------------------------------------
  166. MCControlModule/Module_FrameOpen
  167.  
  168.    NAME
  169.                  Module_FrameOpen -- Prepare for frame read/write
  170.  
  171.    SYNOPSIS
  172.                  Error   = Module_FrameOpen(Slot)
  173.                  D0                          D0
  174.  
  175.                  (ULONG) = Module_FrameOpen(UWORD);
  176.  
  177.    INPUTS
  178.                  Slot: (0-x) Number of slot to access!
  179.  
  180.    RESULT
  181.                   0 = No Error
  182.                   1 = Slot not available
  183.                  -1 = Other Error (you shouldn´t need to use this)
  184.  
  185.    FUNCTION
  186.                  No special function. Just do what is required to
  187.                  access the given slot. Standard.mcm is using this
  188.                  function to active the select line of the given
  189.                  slot. RamCard.mcm is resetting data buffers only.
  190.    SEE ALSO
  191.                  Module_FrameClose()
  192. ;----------------------------------------------------------------------------
  193. MCControlModule/Module_FrameClose
  194.  
  195.    NAME
  196.                  Module_FrameClose -- frame read/write done
  197.  
  198.    SYNOPSIS
  199.                  Module_FrameClose()
  200.  
  201.    FUNCTION
  202.                  No special function. Just do what is required after
  203.                  reading a frame. Standard.mcm is using this
  204.                  function to deactive all select lines slot.
  205.    SEE ALSO
  206.                  Module_FrameOpen()
  207. ;----------------------------------------------------------------------------
  208. MCControlModule/Module_ReadCommand
  209.  
  210.    NAME
  211.                  Module_ReadCommand -- Send command and get answer
  212.  
  213.    SYNOPSIS
  214.                  Result = Module_ReadCommand(Command)
  215.                  D0                          D0
  216.  
  217.                  BYTE   = Module_ReadCommand(BYTE)
  218.  
  219.    FUNCTION
  220.                  Command will be transfered to memory card. The
  221.                  card answer will be returned to Result.
  222.  
  223.    NOTES
  224.                  There is no need to implement different routines
  225.                  for Module_ReadCommand and Module_WriteCommand.
  226.                  Internaly these commands are working equal. The
  227.                  only difference is that the ReadCommand is used
  228.                  when reading frames and the WriteCommand on writing
  229.                  frames. This allows to use different delays for
  230.                  reading and writing. If you hardware isn´t using
  231.                  any different delays use the same routine
  232.                  for both commands.
  233.  
  234.    SEE ALSO
  235.                  Module_WriteCommand()
  236. ;----------------------------------------------------------------------------
  237. MCControlModule/Module_WriteCommand
  238.  
  239.    NAME
  240.                  Module_WriteCommand -- Send command and get answer
  241.  
  242.    SYNOPSIS
  243.                  Result = Module_WriteCommand(Command)
  244.                  D0                           D0
  245.  
  246.                  BYTE = Module_WriteCommand(BYTE)
  247.  
  248.    FUNCTION
  249.                  Command will be transfered to memory card. The
  250.                  card answer will be returned to Result.
  251.  
  252.    NOTES
  253.                  There is no need to implement different routines
  254.                  for Module_ReadCommand and Module_WriteCommand.
  255.                  Internaly these commands are working equal. The
  256.                  only difference is that the ReadCommand is used
  257.                  when reading frames and the WriteCommand on writing
  258.                  frames. This allows to use different delays for
  259.                  reading and writing. If you hardware isn´t using
  260.                  any different delays use the same routine
  261.                  for both commands.
  262.                        
  263.    SEE ALSO
  264.                  Module_ReadCommand()
  265. ;----------------------------------------------------------------------------
  266. MCControlModule/Module_PADOpen
  267.  
  268.    NAME
  269.                  Module_PADOpen -- Prepare for PAD emulation
  270.  
  271.    SYNOPSIS
  272.                  Error   = Module_PADOpen()
  273.                  d0
  274.  
  275.                  (LONG)  = Module_PADOpen()
  276.  
  277.    RESULT
  278.                  0 = No Error
  279.  
  280.    FUNCTION
  281.                  Again! There is no predefined function for this
  282.                  function. Just do what is required or even nothing.
  283.                  Standard.mcm is using this function to set all
  284.                  IO ports to output.
  285.    SEE ALSO
  286.                  Module_PADClose()
  287. ;----------------------------------------------------------------------------
  288. MCControlModule/Module_PADClose
  289.  
  290.    NAME
  291.                  Module_PADClose -- PAD emulation done
  292.  
  293.    SYNOPSIS
  294.                  Module_PADClose()
  295.  
  296.    FUNCTION
  297.                  Again there is no predefined function for this
  298.                  function. Just do what is required or even nothing.
  299.                  Standard.mcm is using this function to reset all
  300.                  IO ports to default.
  301.    SEE ALSO
  302.                  Module_PADClose()
  303. ;----------------------------------------------------------------------------
  304. MCControlModule/Module_PADCommand
  305.  
  306.    NAME
  307.                  Module_PADCommand -- Simulate PAD
  308.  
  309.    SYNOPSIS
  310.                  Module_PADCommand(Command,Answer)
  311.                                    D0,     D1
  312.  
  313.                  Module_PADCommand(BYTE   ,BYTE)
  314.         
  315.    FUNCTION
  316.                  Well, this is a little tricky. You must send the
  317.                  Command on the command line, while simulating
  318.                  an PSX Pad answer on the Dataline by using Answer.
  319.                         
  320.                  The card will think its hearing the playstation is
  321.                  talking to a card and vice versa.
  322.    SEE ALSO
  323.                  Module_PADOpen(), Module_PADClose()
  324. ;----------------------------------------------------------------------------
  325.